The vault paid nothing, and then told him the pool was empty - #235

Two reasons, and the second is the one that needed doing.

The branch was cut before #235 landed, so it was describing a repo that has
since gained lib/server/vaultChain.ts and a vault payout path that no longer
does two on-chain writes in one request. A documentation branch that is behind
main is documentation that is already wrong.

It also retriggers the preview deployment. The one for d8297cf errored with a
build log that stops dead after 'Cloning completed: 50.039s' — no install, no
next build, no error, nothing. Zero build output on a diff that adds one
markdown file, while the GitHub checks workflow passed on the same SHA and every
other deployment that day went green. That is a stall on Vercel's side, not
something in the change, and it never retried on its own.

The branch was cut before #235, so the file described a repo that no longer
exists: 44 routes (now 45), a lib/server/ list with no vaultChain or vaultSweep,
a cron that only closes seasons, and no mention of test:vaultpay.

Three conventions added to §6, because they are exactly the kind this file is
for — each one is a bug that already shipped and would have been avoided by a
sentence:

  - two on-chain writes in one player request is how a solved vault paid
    nothing; the second write was rejected at the RPC boundary before it was a
    transaction, and only the first winner of each week ever took that path
  - anything that can leave a reward unpaid needs a server-side sweep, because
    the vault's only recovery was re-clearing Bunker 5 to reach the door
  - never name a cause you did not check: the payout blamed an empty pool it had
    never read

A documentation branch that is behind main is documentation that is already
wrong, which is the failure invariant #2 in this same file exists to name.

…lib/ (#234)

Every convention in this repo that matters is written down somewhere, and no two
of them are in the same place. The engine boundary is explained in the header of
lib/constants/game-config.ts. The invariants are §10 of a 67KB design doc. The
reason CI does not run lint is a comment in a workflow file. The reason wagmi
mounts as a sibling rather than a wrapper is thirty lines of Web3Providers.tsx,
and that note exists because somebody had already undone it once.

That is fine for whoever wrote all of it. It is not fine for an assistant
opening the repo cold, which is exactly who keeps being handed these tasks: it
reads the file it was pointed at, does not read the four other files explaining
why that file is shaped the way it is, and helpfully simplifies something back
into the bug it was written to fix.

CLAUDE.md collects the parts that are load-bearing and cheap to violate:

  THE BOUNDARY, first, because everything else follows from it. Fourteen plain
  <script> files under public/ that next build never touches, cannot import from
  lib/, and whose syntax errors ship. The duplicated marketplace list is a
  consequence, not an oversight, and the engine's copy wins.

  THE INVARIANTS from GAME-DESIGN.md §10 verbatim, plus the ones the tooling
  already enforces but nobody would guess: one owner for the RPC endpoint and
  one for the origin, and an attribution tag that CANNOT be backfilled.

  WHAT THE CHECK SCRIPTS ARE. Not a test suite. Each one is a bug that already
  shipped, wearing a filename. check:cssvars exists because a primary button
  rendered as near-black text on a dark modal; check:copy exists because "Add
  Cash" reached four files and a "Connect wallet" line sat permanently on
  /profile. Listing them next to what they guard is what stops the next person
  from deleting the noisy one.

  THE MINIPAY RULES that live in copy and in .npmrc, which look like style
  preferences and are listing-review rejections.

  THE COMMIT STYLE, described from the log rather than prescribed.

  THREE SERVER RULES from the vault payout work in #235, added before this
  merged because a documentation branch that is behind main is documentation
  that is already wrong: never put two on-chain writes in one player request;
  anything that can leave a reward unpaid needs a server-side sweep; never name
  a cause you did not check.

Verified against the source rather than the README: the env section names
FIREBASE_SERVICE_ACCOUNT, which is what firebase-config.ts actually reads, while
the README says FIREBASE_SERVICE_ACCOUNT_JSON, which nothing does. Route count,
engine script count and load order, gitignored min/ output, and the audit's
one-place-allowed rules for celoRpc.ts and siteUrl.ts were each read off the
files. No source file changed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>